/* ========================================================================= */
/* ------------------------------------------------------------------------- */
/*!
  \file			pgscript.h
  \date			Aug 2011
  \author		TNick

  \brief		Contains definiions for the project

*//*

 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Please read COPYING and README files in root folder
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*/
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
#ifndef __MAIN_PGS_INC__
#define __MAIN_PGS_INC__
//
//
//
//
/*  INCLUDES    ------------------------------------------------------------ */

#include	<QDebug>
#include	<QtCore/QtGlobal>


/*  INCLUDES    ============================================================ */
//
//
//
//
/*  DEFINITIONS    --------------------------------------------------------- */

/* a simple result system for functions that allow warnings, too */
#ifndef	OUT_SUCCESS

/**
*	@brief	describes the result of a function
*/
enum	OUTCOME			{
	OUTCOME_WARNING = -1,
	OUTCOME_OK = 0,
	OUTCOME_ERROR = 1
};

/**
*	@brief	tests the result for success (warnings included)
*/
#define		OUT_SUCCESS( o )	( o != OUTCOME_ERROR )

/**
*	@brief	tests the result for success (warnings excluded)
*/
#define		OUT_FULL_SUCCESS( o )	( o == OUTCOME_OK )

#endif






/* used to export functions when in library mode */
#if defined(EXPORT_PGSCRIPT)
#  define		EXPORT Q_DECL_EXPORT
#else
#  define		EXPORT Q_DECL_IMPORT
#endif




/* simple system to allow other systems than UserMsg */
#if defined(USE_USERMSG)
#	define	ERROR_REPORT(um,msg)	um.add( UMSG::MSG_ERROR, msg)
#	define	DEBUG_REPORT(um,msg)	um.add( UMSG::MSG_DBG_ERROR, msg)
#else
#	define	ERROR_REPORT(um,msg)	qDebug() << "ERROR!!! " << msg;
#	define	DEBUG_REPORT(um,msg)	qDebug() << "DEBUG: " << msg;
#endif


/* this allows customisation of the name of the UserMsg class for error report */
#ifndef	UMSG
#	define	UMSG	UserMsg
#endif



namespace	PgSave	{
class	IPgSave;
}

namespace	PgScr		{

class		UserVar;
class		UserFunc;
struct		Session;


/**
 * @brief The VarGet structure is used to communicate data through various
 *	functions
 */
struct		VarGet		{
	QString 		s_name;		/**< [in] the name to search for */
	UserVar *		the_var;	/**< [out] the variable */

#if defined(USE_USERMSG)
	UMSG			um;			/**< corelation message structure */
#endif

	VarGet( const QString & s___name )
	{
		s_name = s___name;
		the_var = NULL;
	}
};



/**
 * @brief The FncGet structure is used to communicate data through various
 *	functions
 */
struct		FncGet		{
	QString			s_name;		/**< [in] the name to search for */
	UserFunc *		the_fun;	/**< [out] the function */

#if defined(USE_USERMSG)
	UMSG			um;			/**< corelation message structure */
#endif

	FncGet( const QString &	s___name )
	{
		s_name = s___name;
		the_fun = NULL;
	}
};




/**
*	@brief	 user function to search modules for a variable
*/
typedef OUTCOME			(*findVariableStruct)	( VarGet & in_out );


/**
*	@brief	 user function to search modules for a variable
*/
typedef UserVar *		(*findVariableName)		( const QString & var_n );


/**
*	@brief	 user function to search modules for a function
*/
typedef OUTCOME			(*findFunctionStruct)	( FncGet & in_out );


/**
*	@brief	 user function to search modules for a function
*/
typedef UserFunc *		(*findFunctionName)		( const QString & var_n );



/*  DEFINITIONS    ========================================================= */
//
//
//
//
/*  DATA    ---------------------------------------------------------------- */


/*  DATA    ================================================================ */
//
//
//
//
/*  FUNCTIONS    ----------------------------------------------------------- */


/**
*	@brief	 Initialisation of the library
*/
EXPORT void				initialise				( void );


/**
*	@brief	 Un-initialisation of the library
*/
EXPORT void				terminate				( void );




/**
*	@brief	 Creates a new session
*/
EXPORT Session*			createSession			( void );


/**
*	@brief	 Deletes a session; fails if it is the current session
*/
EXPORT void				deleteSession			( Session * targ_ss );


/**
*	@brief	 Changes the current session
*/
EXPORT void				makeSessionCurrent		( Session * targ_ss );


/**
*	@brief	 reports current session
*/
EXPORT Session *		currentSession			( void );







/**
*	@brief	saves a list of sessions to provided interface
*
*	The interface is assumed to have the current path set to the folder
*	that will contain the folder for sessions; the function will create the
*	folder and iterate the list, creating one folder for each
*
*	@param	s_name	the name to use for this list
*	@param	p_array	pointer to the array of sessions
*	@param	cnt		number of elements in the array
*	@param	targ_i	the interface to use
*/
EXPORT void			saveSessionList				(
		QString				s_name,
		Session **			p_array,
		int					cnt,
		PgSave::IPgSave &	targ_i
		);


/**
*	@brief	saves a list of sessions to provided interface
*
*	The interface is assumed to have the current path set to the folder
*	that will contain the folder for sessions; the function will create the
*	folder and iterate the list, creating one folder for each
*
*	@param	s_name	the name to use for this list
*	@param	p_array	list of sessions
*	@param	targ_i	the interface to use
*/
EXPORT void			saveSessionList				(
		QString				s_name,
		QList<Session *> &	p_array,
		PgSave::IPgSave &	targ_i
		);


/**
*	@brief	saves a session to provided interface
*
*	The interface is assumed to have the current path set to the folder
*	that will contain the session; the function will create the
*	folder and save things
*
*	@param	s_name	the name to use for this session
*	@param	ses		the session to save
*	@param	targ_i	the interface to use
*/
EXPORT void			saveSession					(
		QString				s_name,
		Session *			ses,
		PgSave::IPgSave &	targ_i
		);


/**
*	@brief	loads a list of sessions from provided interface
*
*	The interface is assumed to have the current path set to the folder
*	that contains the sessions; the function will iterate the components
*	and assume each folder is a session folder.
*
*	The function will allocate the memory for the array.
*
*	@param	cnt		number of elements in the array
*	@param	targ_i	the interface to use
*
*	@return	either a pointer to an array or NULL if no session was loaded
*/
EXPORT Session **		loadSessionList				(
		int &				cnt,
		PgSave::IPgSave &	targ_i
		);


/**
*	@brief	loads a list of sessions from provided interface
*
*	The interface is assumed to have the current path set to the folder
*	that contains the sessions; the function will iterate the components
*	and assume each folder is a session folder.
*
*	The sessions that are succesfully created are appended to provided list.
*	The list is not otherwise altered (not cleared, for example).
*
*	@param	p_array	list of sessions
*	@param	targ_i	the interface to use
*/
EXPORT void			loadSessionList				(
		QList<Session *> &	p_array,
		PgSave::IPgSave &	targ_i
		);


/**
*	@brief	loads a session from provided interface
*
*	the interface is assumed to have the current path set to the folder
*	that contains the session; the function will enter the session folder
*	itself
*
*	@param	s_name	the name of the session
*	@param	targ_i	the interface to use
*
*	@return		NULL if failure, the pointer to newly created sessions
*/
EXPORT Session *		loadSession					(
		QString				s_name,
		PgSave::IPgSave &	targ_i
		);






/*  FUNCTIONS    =========================================================== */
//
//
//
//

}	// namespace	PgScr

#endif // __MAIN_PGS_INC__
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
